<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python documentation Index' />
<link rel="first" href="lib.html" title='Python library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="elementtree-elementtree-objects.html" />
<link rel="prev" href="module-xml.etree.ElementTree.html" />
<link rel="parent" href="module-xml.etree.ElementTree.html" />
<link rel="next" href="elementtree-elementtree-objects.html" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name='aesop' content='information' />
<title>8.13.1 Functions</title>
</head>
<body>
<div class="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="8.13 xml.etree.ElementTree  "
  href="module-xml.etree.ElementTree.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="8.13 xml.etree.ElementTree  "
  href="module-xml.etree.ElementTree.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="8.13.2 elementtree Objects"
  href="elementtree-elementtree-objects.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-xml.etree.ElementTree.html">8.13 xml.etree.ElementTree  </a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-xml.etree.ElementTree.html">8.13 xml.etree.ElementTree  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="elementtree-elementtree-objects.html">8.13.2 ElementTree Objects</a>
</div>
<hr /></div>
</div>
<!--End of Navigation Panel-->

<h2><a name="SECTION00101310000000000000000"></a><a name="elementtree-functions"></a>
<br>
8.13.1 Functions
</h2>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1974' xml:id='l2h-1974' class="function">Comment</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>text</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Comment element factory.  This factory function creates a special
element that will be serialized as an XML comment.
The comment string can be either an 8-bit ASCII string or a Unicode
string.
<var>text</var> is a string containing the comment string.

<p>
<dl><dt><b><tt>Returns:</tt></b></dt>
<dd>
An element instance, representing a comment.
</dd></dl>
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1975' xml:id='l2h-1975' class="function">dump</tt></b>(</nobr></td>
  <td><var>elem</var>)</td></tr></table></dt>
<dd>
Writes an element tree or element structure to sys.stdout.  This
function should be used for debugging only.

<p>
The exact output format is implementation dependent.  In this
version, it's written as an ordinary XML file.

<p>
<var>elem</var> is an element tree or an individual element.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1976' xml:id='l2h-1976' class="function">Element</tt></b>(</nobr></td>
  <td><var>tag</var><big>[</big><var>, attrib</var><big>]</big><var></var><big>[</big><var>, **extra</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Element factory.  This function returns an object implementing the
standard Element interface.  The exact class or type of that object
is implementation dependent, but it will always be compatible with
the _ElementInterface class in this module.

<p>
The element name, attribute names, and attribute values can be
either 8-bit ASCII strings or Unicode strings.
<var>tag</var> is the element name.
<var>attrib</var> is an optional dictionary, containing element attributes.
<var>extra</var> contains additional attributes, given as keyword arguments.

<p>
<dl><dt><b><tt>Returns:</tt></b></dt>
<dd>
An element instance.
</dd></dl>
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1977' xml:id='l2h-1977' class="function">fromstring</tt></b>(</nobr></td>
  <td><var>text</var>)</td></tr></table></dt>
<dd>
Parses an XML section from a string constant.  Same as XML.
<var>text</var> is a string containing XML data.

<p>
<dl><dt><b><tt>Returns:</tt></b></dt>
<dd>
An Element instance.
</dd></dl>
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1978' xml:id='l2h-1978' class="function">iselement</tt></b>(</nobr></td>
  <td><var>element</var>)</td></tr></table></dt>
<dd>
Checks if an object appears to be a valid element object.
<var>element</var> is an element instance.

<p>
<dl><dt><b><tt>Returns:</tt></b></dt>
<dd>
A true value if this is an element object.
</dd></dl>
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1979' xml:id='l2h-1979' class="function">iterparse</tt></b>(</nobr></td>
  <td><var>source</var><big>[</big><var>, events</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Parses an XML section into an element tree incrementally, and reports
what's going on to the user.
<var>source</var> is a filename or file object containing XML data.
<var>events</var> is a list of events to report back.  If omitted, only ``end''
events are reported.

<p>
<dl><dt><b><tt>Returns:</tt></b></dt>
<dd>
A (event, elem) iterator.
</dd></dl>
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1980' xml:id='l2h-1980' class="function">parse</tt></b>(</nobr></td>
  <td><var>source</var><big>[</big><var>, parser</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Parses an XML section into an element tree.
<var>source</var> is a filename or file object containing XML data.
<var>parser</var> is an optional parser instance.  If not given, the
standard XMLTreeBuilder parser is used.

<p>
<dl><dt><b><tt>Returns:</tt></b></dt>
<dd>
An ElementTree instance
</dd></dl>
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1981' xml:id='l2h-1981' class="function">ProcessingInstruction</tt></b>(</nobr></td>
  <td><var>target</var><big>[</big><var>, text</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
PI element factory.  This factory function creates a special element
that will be serialized as an XML processing instruction.
<var>target</var> is a string containing the PI target.
<var>text</var> is a string containing the PI contents, if given.

<p>
<dl><dt><b><tt>Returns:</tt></b></dt>
<dd>
An element instance, representing a PI.
</dd></dl>
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1982' xml:id='l2h-1982' class="function">SubElement</tt></b>(</nobr></td>
  <td><var>parent, tag</var><big>[</big><var>, attrib</var><big>]</big><var> </var><big>[</big><var>, **extra</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Subelement factory.  This function creates an element instance, and
appends it to an existing element.

<p>
The element name, attribute names, and attribute values can be
either 8-bit ASCII strings or Unicode strings.
<var>parent</var> is the parent element.
<var>tag</var> is the subelement name.
<var>attrib</var> is an optional dictionary, containing element attributes.
<var>extra</var> contains additional attributes, given as keyword arguments.

<p>
<dl><dt><b><tt>Returns:</tt></b></dt>
<dd>
An element instance.
</dd></dl>
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1983' xml:id='l2h-1983' class="function">tostring</tt></b>(</nobr></td>
  <td><var>element</var><big>[</big><var>, encoding</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Generates a string representation of an XML element, including all
subelements.
<var>element</var> is an Element instance.
<var>encoding</var> is the output encoding (default is US-ASCII).

<p>
<dl><dt><b><tt>Returns:</tt></b></dt>
<dd>
An encoded string containing the XML data.
</dd></dl>
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1984' xml:id='l2h-1984' class="function">XML</tt></b>(</nobr></td>
  <td><var>text</var>)</td></tr></table></dt>
<dd>
Parses an XML section from a string constant.  This function can
be used to embed ``XML literals'' in Python code.
<var>text</var> is a string containing XML data.

<p>
<dl><dt><b><tt>Returns:</tt></b></dt>
<dd>
An Element instance.
</dd></dl>
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1985' xml:id='l2h-1985' class="function">XMLID</tt></b>(</nobr></td>
  <td><var>text</var>)</td></tr></table></dt>
<dd>
Parses an XML section from a string constant, and also returns
a dictionary which maps from element id:s to elements.
<var>text</var> is a string containing XML data.

<p>
<dl><dt><b><tt>Returns:</tt></b></dt>
<dd>
A tuple containing an Element instance and a dictionary.
</dd></dl>
</dl>

<p>

<div class="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="8.13 xml.etree.ElementTree  "
  href="module-xml.etree.ElementTree.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="8.13 xml.etree.ElementTree  "
  href="module-xml.etree.ElementTree.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="8.13.2 elementtree Objects"
  href="elementtree-elementtree-objects.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-xml.etree.ElementTree.html">8.13 xml.etree.ElementTree  </a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-xml.etree.ElementTree.html">8.13 xml.etree.ElementTree  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="elementtree-elementtree-objects.html">8.13.2 ElementTree Objects</a>
</div>
</div>
<hr />
<span class="release-info">Release 2.5.1, documentation updated on 18th April, 2007.</span>
</div>
<!--End of Navigation Panel-->
<address>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</address>
</body>
</html>
